# Request : Web request

The req object represents the HTTP request and has properties for the request query string, parameters, body, HTTP headers, and so on. In this documentation and by convention, the object is always referred to as req (and the HTTP response is res) but its actual name is determined by the parameters to the callback function in which you’re working.

For example:

app.get('/user/:id', function (req, res) {
  res.send('user ' + req.params.id);
});

But you could just as well have:

app.get('/user/:id', function (request, response) {
  response.send('user ' + request.params.id);
});

# Support

The following shows WebRequest module APIs available for each permissions.

# WebRequest Object

WebRequest inherits from HttpServerRequest. For more properties, please refer to the HttpInput module: HttpInput.

# req.app

• app {Object} This WebApp object.

# req.url

• url {String} HTTP request url. This property inherit from HttpServerRequest.

# Example

console.log(req.url);
// /index.html?name=xiaoming&age=22

# req.method

• method {String} Contains a string corresponding to the HTTP method of the request: GET, POST, PUT, and so on. This property inherit from HttpServerRequest.

# req.protocol [for REQUEST]

• {String} HTTP request protocol.

# Example

console.log(req.protocol);
// http or https

This property is supported in EdgerOS 1.10.1 and later.

# req.headers

• headers {Object} HTTP request headers. This property inherit from HttpServerRequest.

# Example

console.log(req.headers.host);
// => 192.168.7.32:8000
console.log(req.headers['accept-language']); 
// => zh-CN,zh;q=0.8

# req.body

• {Object | Buffer | String} request body, default: {}.

Contains key-value pairs of data submitted in the request body. By default, it is {}, and is populated when you use bodyParser middleware such as bodyParser.json() or webbodyparser.urlencoded().

You can cache request data to body as Buffer object, see input.enableCache().

# Example

The following example shows how to use body-parsing middleware to populate req.body.

var bodyParser = require('middleware').bodyParser;

app.use(bodyParser.json()); // for parsing application/json
app.use(bodyParser.urlencoded()); // for parsing application/x-www-form-urlencoded

app.post('/profile', function (req, res, next) {
  console.log(req.body)
  res.json(req.body);
})

# req.path

• path {String} Contains the path part of the request URL.

// example.com/users?sort=desc
console.log(req.path)
// => /users

# req.params

• params {Object} This property is an object containing properties mapped to the route parameters.

# Example

If you have the route /user/:name, then the “name” property is available as req.params.name. This object defaults to {}.

// GET /user/tj
console.log(req.params.name);
// => 'tj'

When you use a regular expression for the route definition, capture groups are provided in the array using req.params[n], where n is the nth capture group. This rule is applied to unnamed wild card matches with string routes such as /file/*:

// GET /file/javascripts/jquery.js
console.log(req.params[0]);
// => 'javascripts/jquery.js'

# req.query

• query {Object} This property is an object containing a property for each query string parameter in the route. If there is no query string, it is the empty object, {}.

# Example

// GET /search?q=tobi+ferret
console.log(req.query.q)
// => 'tobi ferret'

# req.cookies

• cookies {Object}

This property is an object that contains cookies sent by the request. If the request contains no cookies, it defaults to {}.

# Example

// Cookie: name=tj
console.log(req.cookies.name);
// => 'tj'

# req.get(field)

• field {String} Header field.
• Returns the specified HTTP request header field value.

Returns the specified HTTP request header field (case-insensitive match). The Referrer and Referer fields are interchangeable.

# Example

req.get('Content-Type');
// => "text/plain"

req.get('Something');
// => undefined

# req.header(field)

• field {String} Header field.
• Returns the specified HTTP request header field value.

Aliased of req.get(field).

# req.param(name, defaultValue)

• name {String}
• defaultValue {}
• Returns the value of param name when present.

Deprecated. Use either req.params, or req.query, as applicable.

Lookup is performed in the following order:

• req.params
• req.query

Optionally, you can specify defaultValue to set a default value if the parameter is not found in any of the request objects.

Direct access to req.params, and req.query should be favoured for clarity - unless you truly accept input from each object.

# Example

// ?name=tobi
req.param('name');
// => "tobi"

// /user/tobi for /user/:name
req.param('name');
// => "tobi"

# Events

# data

When HTTP body is received from the client a data event is emitted with a buf object:

• buf {Buffer} Receive from client.

# end

When all body data is received or there is no body data a end event is emitted.

# close

A close event is emitted when the request disconnected. Request may be closed normally or not properly, so the end event may not be emitted before the close event.

# error

A close event is emitted when the error occurs.